home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / telecomm / fnordadl / fn132src.zoo / README.src < prev   
Encoding:
Text File  |  1991-09-02  |  11.4 KB  |  250 lines
  1.  
  2.     -----------------------------------
  3.     FNORDADEL 1.32 SOURCES DISTRIBUTION
  4.     -----------------------------------
  5.  
  6.     This archive contains the full source code for the Fnordadel programs and
  7. documentation.  Here is a list of what's what:
  8.  
  9. README.src    This file.
  10. citalt/        (DIR) Peripheral programs; not part of the general distribution.
  11. cith/        (DIR) Header files.
  12. citlib/        (DIR) Library sources.
  13. citmain/    (DIR) Sources for citadel.tos and configur.tos.
  14. citutil/    (DIR) Sources for all distributed utilities.
  15. ctdlcnfg.doc    Documented configuration file.
  16. fnordbug    Current list of known bugs.
  17. fnorddoc    Current list of suggestions for the documentation.
  18. fnordsug    Current list of suggestions for improvements to Fnordadel.
  19. increm        Current increm (incremental change documentation; IMPORTANT!).
  20. increm.1    Old increm file.
  21. increm.2         -ditto-
  22. increm.3         -ditto-
  23. increm.4         -ditto-
  24. makefile    The master makefile.
  25. man/        (DIR) Nroff sources for the man pages.
  26. ref-man/    (DIR) Texinfo sources for the Reference Manual.
  27. scripts/    (DIR) Various shell scripts, for Unix shells and Gulam (ST).
  28.  
  29. citalt:
  30. citpeek.c    Program to get down and dirty with system files; debugging aid.
  31. dumpmsg.c    Dump pieces of message base to the screen.
  32. runit.c        Old STadel prg to run the BBS; a kind of specialised mini-shell
  33. spooledt.c    Old STadel prg for editing network spool files.
  34. users.c        Old STadel prg to postprocess clog output.
  35.  
  36. cith:
  37. *.h        C header files, included by all Fnordadel programs.
  38.  
  39. citlib:
  40. *.c        C source files for the Fnordadel library.  The Makefile links
  41.         all binaries against this library to pick up commonly used
  42.         low-level code.
  43.  
  44. citmain:
  45. *.c        C source files for citadel and configur.
  46.  
  47. citutil:
  48. *.c        C source files for all distributed utility programs.
  49.  
  50. man:
  51. Makefile    The Makefile (generates *.man from *.1)
  52. manfilt.c    A quick hack to filter excess blank lines from formatted man
  53.         pages.  You may not need this.
  54. *.1        Nroff sources for man pages.
  55.  
  56. ref-man:
  57. Makefile    A Makefile for the Reference Manual.
  58. *.tex        Texinfo source files for the Manual.
  59.  
  60. scripts:
  61. bbs.g        A Gulam script to run the BBS.
  62. ldt*        Unix shellscript to make a file listing all sources.
  63. makedist*    Unix shellscript to build a distribution; use after `setupdist'.
  64. manbak*        Unix shellscript to make a quickie manual backup.
  65. manbak.g    Gulam version of above.
  66. setupdist*    Unix shellscript to set up a distribution directory.
  67. srcbak*        Unix shellscript to make a quickie sources backup.
  68. srcbak.g    Gulam version of above.
  69.  
  70.  
  71.     How to build Fnordadel
  72.     ----------------------
  73.  
  74.     This is the scary bit. (-:  Firstly, some requirements.  Fnordadel is
  75. written in ANSI C.  We use the GCC compiler, but there are other ANSI
  76. compilers for the ST (Turbo C, to name one).  We use Eric Smith's MiNT library
  77. with it, although bammi's GCC libs should work fine.  We make no guarantee
  78. that things will work using different libs under GCC or another compiler,
  79. but we don't think we've done anything gross to make it lib-specific or
  80. anything.
  81.  
  82.     Assuming that the first paragraph didn't get you, here's how to build
  83. Fnordadel:
  84.  
  85.     1) Unpack the rest of this archive, if you haven't already.  You'll find
  86.        the directory structure as listed above.
  87.     2) Edit the makefile to point make at the binaries for your compiler.  We
  88.        compile Fnordadel on a NeXT running a GCC cross-compiler, but we also
  89.        compile on the ST.  Take your pick, or if you're using another compiler,
  90.        try it.
  91.     3) Take a look at the various targets defined in the makefile.  Among the
  92.        more popular options are `make minimum' to build citadel and configur,
  93.        and `make remake' to build the whole bloody thing.  We suggest the
  94.        first one, for starters.
  95.  
  96.     If you tried a make in step 3 and it worked, you should have binaries in
  97. citmain called citadel.tos and configur.tos.  Try running them.  If all works,
  98. run a make remake to build the whole lot.
  99.  
  100.     If you tried a make and it didn't work, you're out of luck. (-:  No,
  101. seriously... 
  102.  
  103.     o If make cannot find the compiler binaries, you'll find out pretty
  104. quick.  If you're using GCC, make sure you have the GCCEXEC environment
  105. variable set correctly (using a command like `SETENV GCCEXEC c:\bin\gcc-').
  106.  
  107.     o If the gcc archiver (gcc-ar) dies while make is trying to build
  108. libfnord.olb, you might have one of the buggy versions.  Make will crap out,
  109. and you can manually rename a temporary file you'll find lying about in
  110. citlib to `libfnord.olb' and restart the make.  This is annoying, so get a
  111. fresh copy of the gcc-ar.
  112.  
  113.     o If make craps out on you at a random point with `out of memory' errors,
  114. just restart it.  ST versions of GNU-Make have some sort of memory leak which
  115. causes harmless but annoying sudden stops.
  116.  
  117.     o If something else craps out, you're on your own.  If you have the same
  118. setup as we do, things should go smoothly.  If you have a different setup,
  119. we can try to help, but no guarantees.  Send some mail.
  120.  
  121.  
  122.     What to do with it once it's built
  123.     ----------------------------------
  124.  
  125.     There are a few things you can do with the Fnordadel sources once you've
  126. got them built.
  127.  
  128.     1) Erase them, since it was all just an academic exercise. (-:
  129.  
  130.     2) Use them to keep up with new Fnordadel releases.  We will be releasing
  131.        updates to Fnordadel in source and binary form; getting the source
  132.        patches and building your own binaries will probably be cheaper in
  133.        terms of the amount of stuff you'll have to download or transfer to
  134.        get the new versions.
  135.  
  136.     3) Hack on it yourself.  We don't discourage this, but we would like to
  137.        emphasize that we'd really like to keep Fnordadel a relatively stable
  138.        system.  You are perfectly entitled to take Fnordadel, change a few
  139.        things, change the name and release a new system, but please don't
  140.        unless it's really radical stuff.  A much better approach is to hack
  141.        in the things you want and then send us diffs; chances are good that
  142.        we'll merge them with the official version.
  143.  
  144.        If you do plan to hack on Fnordadel, best to ask us before you start --
  145.        we may already have hacked in the thing you want and just not told
  146.        anyone yet, or we might know of someone else who's doing the same
  147.        thing already.  Duplicated effort benefits no-one.
  148.  
  149.  
  150.     Fnordadel development conventions
  151.     ---------------------------------
  152.  
  153.     We maintain a few files to help the development process.  We list them
  154. here:
  155.  
  156.     o fnordbug -- this is a list of all known bugs.  Bug reports are
  157.       logged in here, preferably with an attribution (i.e., who reported it).
  158.       When a bug is fixed, the version in which the fix went in is added
  159.       beside the bug.  When we're confident that the fix works, we remove
  160.       the bug from the list.
  161.     o fnordsug -- same sort of thing as fnordbug, only for suggestions instead
  162.       of bugs.  We put the version number where a suggestion was implemented,
  163.       and leave it around until we're sure it works.
  164.     o fnorddoc -- same thing again, only this time for documention glitches
  165.       and/or suggestions.
  166.  
  167.     o increm -- Anything done to Fnordadel is logged in increm.  Each change
  168.       is logged under a header listing the date, the version number and files
  169.       affected.  Every so often when a new public or beta release goes out,
  170.       it is renamed to increm.X where X is a number, and a new one is started.
  171.       These increm files are transcribed by us into increm.doc, which is a
  172.       version of increm written in English rather than hackerese for the
  173.       benefit of the sysops.
  174.  
  175.     Another thing you should know about: the version numbering scheme.  The
  176. version number of citadel.tos is comprised of a version string, VERSION, and
  177. a patch number, PATCHNUM.  The former is defined in citlib/version.c, and is
  178. changed rarely; changing the version number indicates a major change to
  179. system files or something like that.  The patch number, on the other hand,
  180. changes every single time a change or batch of changes is made, no matter how
  181. minute.  The idea is that no incompatible system file changes are made
  182. within a given version; i.e., utility binaries compiled under some revision
  183. of version x.yz will work with any citadel/configur binaries from the
  184. same version; if an incompatibility is introduced (like a change to the log
  185. file, net file or similar), we must bump the version number.  Simple, huh?
  186. In actual practice, sometimes we make changes that are tiny and don't seem
  187. to warrant upping the version number, but which nonetheless render utility
  188. binaries incompatible due to a change in ctdltabl.sys format.  This is a
  189. weakness whcih must be addressed.
  190.  
  191.  
  192.     How to build the Reference Manual
  193.     ---------------------------------
  194.  
  195.     To build the Manual you need a few things that aren't included here.  You
  196. will first off need a working TeX system.  TeX is available for the ST,
  197. and it's a standard piece of software on most Unix sites, so if you have
  198. access to a Unix box (especially one with a laser printer) you may be in
  199. luck.  Once you've found a TeX system, or got the TeX stuff for your ST and
  200. installed it and figured out how it works (no easy thing), you then have to
  201. get ahold of the GNU Texinfo system.  It's available at secret and RT, and
  202. at many sites on the Internet.  It consists of a file of TeX macros called
  203. texinfo.tex, and a bunch of other stuff (like macros for the Emacs text
  204. editor) that you don't have to worry about.
  205.  
  206.     In order to process the Manual and get the nice typeset output for a
  207. laser printer, simply put texinfo.tex in the search path of TeX and say
  208. `make fnord.dvi'.  Make will run TeX three times (this is slow as molasses,
  209. we know, but it's necessary) and produce fnord.dvi, which is the
  210. device-independent file of TeX output which can then be printed on any
  211. sort of high-res output device.
  212.  
  213.     In order to get the ASCII version of the manual (the one that comes in
  214. the fnXXXman.zoo archive), you'll need even more stuff.  Adrian (elim@secret)
  215. has hacked the Texinfo macros to work in conjunction with a program called
  216. `dvidoc', which takes a TeX DVI file and produces an ASCII approximation of
  217. it.  The hacked texinfo.tex adjusts all the fonts to one boring font, and
  218. changes a bunch of other things.  The modified texinfo.tex is called
  219. `docinfo.tex', and is available at secret and RT.  You also need the dvidoc
  220. program, available at the same places.  When you have these things, you
  221. can say `make fnord.doc' and out will come a file of plain ASCII text
  222. called fnord.doc.  (You will notice that the pagination is different between
  223. the nice typeset version and the ASCII version; this is because of the
  224. different fonts and page size set in docinfo.tex as opposed to texinfo.tex.
  225. Notice that all the index entries and cross-references are properly
  226. adjusted...neat, huh?)
  227.  
  228.  
  229.     Formatting the man pages
  230.     ------------------------
  231.  
  232.     In the man directory is a set of nroff source files (*.1), a Makefile and
  233. a small C program called manfilt.c.  Manfilt was hacked together because the
  234. nroff on our NeXT likes to put large numbers of spurious blank lines in the
  235. output; this program filters them out.  If you're on a Unix box, you should
  236. have no problem with these things (just type `make').  If you're on an ST,
  237. you'll have to get ahold of some version of nroff.  Try Bill Rosencranz's
  238. version.
  239.  
  240.     If you have problems
  241.     --------------------
  242.  
  243.     If you have trouble getting any of this stuff to work, you can drop us
  244. a line and we'll try to help.  Good luck.
  245.  
  246.     --Adrian Ashley (elim@secret)
  247.       Royce Howland (Mr. Neutron@RT)
  248.  
  249.       September, 1991
  250.